Summary

Polishes the CLI surface for discoverability and automation. Adds long-form help topics, usage examples on every mutating command, "did you mean" suggestions on typos, humanized auth errors, and a deterministic --no-input path so AI agents / CI scripts never block on interactive prompts.

Rebased onto main now that #84 (PD-6071 browser login) is merged, and squashed into a single commit. The whole diff is the review surface.

Help topics

New lsh help <topic> pages grouped under a dedicated section of lsh --help:

Help topics:
  authentication   How to sign in: tokens, profiles, env vars
  automation       Run lsh non-interactively (CI, scripts, AI agents)
  output-formats   Render results as table or JSON
  profiles         How profiles map to teams

Each topic renders as a clean documentation page (no flag dump under it).

Did-you-mean

$ lsh sever list
Error: unknown command "sever" for "lsh"

Did you mean this?
        servers

(SuggestionsMinimumDistance = 2 on rootCmd.)

Humanized auth errors

utils.PrintError rewrites 401/403 from the API into actionable guidance:

$ LATITUDESH_TOKEN=ak_invalid lsh projects list --no-input
✗ Error: Your authentication token is invalid or revoked.
Run 'lsh login' to sign in again, or see 'lsh help authentication'.

Detection (hasStatusMarker) anchors on the bracketed [<status>] marker the go-openapi runtime emits, which shows up in two real shapes:

• [401] Unauthorized &{...} — generic response (what list endpoints return)
• [POST /servers][401] createServerUnauthorized ... — typed response

It matches [401]/[403] only at the start of the string or right after the ] that closes the [<method> <path>] segment — so both shapes are caught while a bare [401] buried in an error payload is ignored, and loose words like unauthorized (e.g. "field 'role' has an unauthorized value") are never matched. Covered by a table-driven test in internal/utils/response_utils_test.go.

Examples on mutating commands

Every mutating command gained an Example: field (Cobra renders these before flags, matching the clig.dev recommendation): api_keys, servers (create/update/reinstall/destroy/schedule-deletion), projects, ssh_keys, tags, virtual_networks (+ assignments), plus login / auth status / auth logout / completion.

Every example was verified against the command's actual flag set — this caught and fixed real unknown flag bugs where examples used hyphens for flags that are underscore-named (--operating_system, --ssh_keys, --provisioning_type) and a stale --id on projects destroy (real flag is --id_or_slug).

SilenceUsage = true on these commands keeps errors clean (no flag dump under "Error: ...").

Cleaner flag descriptions

Removed hardcoded enum lists from generated flag descriptions (e.g. --operating_system, --plan, --site, --raid, --environment, --provisioning_type). They went stale every time the API added a SKU/region/OS. Replaced with short prose + e.g. <one-example> using the correct dash-separated plan slugs (c2-small-x86).

completion help rewrite

The generated cobra boilerplate (yourprogram, a path that fails on Homebrew) was replaced with per-shell instructions that work for any install method — a portable ~/.zsh/completions + compinit setup for zsh and a ~/.bashrc source line for bash, with Homebrew shortcuts noted alongside.

--no-input for agents and scripts

The --project prompt now respects the existing --no-input global flag. When set (or when stdin is not a TTY), commands that would otherwise open the interactive bubbletea picker exit with an actionable error:

$ lsh --no-input servers list
Error: --project is required (pass --project=<id>, --all-projects, or set LSH_PROJECT)

This matters because the bubbletea picker is not driveable by stdin strings — AI agents running inside a TTY (Claude Code, Aider, etc.) would otherwise hang on it. lsh help automation documents the full non-interactive contract.

Test plan

go build -o ./lsh-dev .

# Help topics + did-you-mean
./lsh-dev --help
./lsh-dev help authentication
./lsh-dev help automation
./lsh-dev sever list                          # → "Did you mean: servers"

# Examples render before flags, with real flag names
./lsh-dev servers create --help               # --operating_system / --ssh_keys, no Enum dump
./lsh-dev projects create --help              # --provisioning_type
./lsh-dev tags create --help

# Non-interactive mode
./lsh-dev --no-input servers list             # errors out, does not prompt
LSH_PROJECT=<id> ./lsh-dev servers list       # uses env, no prompt

# Humanized 401 (no real credentials needed)
LATITUDESH_TOKEN=ak_invalid ./lsh-dev projects list --no-input
# → "Your authentication token is invalid or revoked..."

# Control: a non-auth error is NOT humanized (passes through raw)
LATITUDESH_TOKEN=x ./lsh-dev projects list --no-input --base-path=/nonexistent
# → "[GET /projects] get-projects (status 404): {}"

Notes

• Manual edits to generated *_operation.go files are tagged // MANUAL — keep when regenerating so a future swagger regeneration preserves them.
• Help topic content is plain Cobra commands with a custom help template ({{.Long}}\n) — no third-party doc generator.
• Volume commands were intentionally left untouched (handled in a separate task).

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
cli/create_server_operation.go:41
The OS slug in the minimal deploy example is `ubuntu_22_04`, but the only valid Ubuntu 22.04 slug in `SupportedOperatingSystems` (and the go-openapi enum) is `ubuntu_22_04_x64_lts`. A user copying this example verbatim would hit a validation error. The reinstall command's example already uses the correct slug for comparison.

```suggestion
    --operating_system=ubuntu_22_04_x64_lts \
```

_{Reviews (3): Last reviewed commit: "feat(help): improve CLI help discoverabi..." | Re-trigger Greptile}